home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1998 July
/
EnigmA AMIGA RUN 29 (1998)(G.R. Edizioni)(IT)[!][issue 1998-07 & 08].iso
/
recent
/
warpup1.lha
/
WarpUP-WarpOS
/
hwdrivers
/
WarpHW.txt
Wrap
Text File
|
1998-02-04
|
11KB
|
325 lines
WarpUp hardware driver protocol version 1
© 4.2.1998 HAAGE&PARTNER Gmbh
Written by Sam Jordan
$VER: WarpHW.txt 1.0 (4.2.98)
-----------------------------------------
1. Introduction
---------------
This document describes the WarpUp hardware driver protocol which allows
anyone to write driver software for PowerPC hardware supporting the
WarpUp-HAL for dual processor systems.
The WarpUp-HAL was splitted up since version 3 into two parts, the main
HAL (warp.library) and the hardware driver (warpHW.library). The warp.library
now opens the warpHW.library and calls its functions to get control over
the specific hardware. Note that the hardware drivers only work with
warp.library version 3 and higher.
Every hardware which provides a driver named 'warpHW.library' will work with
the WarpUp-HAL (and therefore with WarpOS). These different libraries can
be distinguished by the tool program 'GetDriverInfo' which prints out the
identification string and the largest protocol number supported. This tool
should always be found with this documentation together. Just run it and
it will print out the information, if the warpHW.library was found.
2. Requirements
---------------
To write a WarpUp hardware driver you need a 68K C compiler, a PPC C compiler
supporting WarpUp and a linker which can deal with the extended hunk format.
StormC supports all this and other compilers might support it in future.
Of course, it's possible to write the driver completely in assembler, but
better use C instead.
The WarpHW.library is a mixed shared library, since it provides functions
for the 68K side and the PowerPC side.
3. API notes
------------
This document describes the protocol version 1, which is the first version
released. If anyone needs more API functions because of special hardware
features or for other reasons, this protocol will be enhanced and new
versions will be released. In this case it's very likely that the HAL itself
must be updated to support the new API. But older hardware drivers will work
without modification, since the WarpUp-HAL will ask the driver for the maximal
protocol version which is supported.
Anyone which requires enhancements to the protocol should contact us, the
appropriate links can be found at the bottom of this document.
4. Template
-----------
In the directory there is a template for a new hardware driver which should
be helpful for development. You will find the following files of importance:
- WarpHW.¶ : 68K-Storm-Project, which is the main project here
- WarpHW_PPC.¶ : PPC-Storm-Project, which is a subproject of WarpHW.¶
- WarpHW.c : C source compiled for 68K, containing the 68K API
functions
- WarpHW_PPC.c : C source compiled for PPC, containing the PPC API
functions
- WarpHW_68K.s : A small 68K assembler function to perform NOP
synchronisation
- WarpHW_PPC_asm.p : Some small PPC assembler functions to perform ISYNC/SYNC
synchronisation and to provide some important
functions for the linker.
- WarpHW_lib.fd : The FD file for the WarpHW.library
First compile the PPC project to gain the object files 'WarpHW_PPC.o' and
'WarpHW_PPC_asm.o'. Afterwards add those object files to the 68K project
and compile the main project. Finally link everything together to a
shared library.
Important Note: Never create a Storm-Project with 'Mixed Binary' option
to write a hardware driver. This can't work because of callbacks to the
powerpc.library/warp.library in the library initialisation of the
warpHW.library. It's the best way to take the template project and to
add the code.
5. Protocol description
-----------------------
This chapter discusses the interaction between the WarpUp-HAL and the
hardware drivers.
a) Evaluating the address of the PowerPC exception area
The WarpUp-HAL needs the location of the PowerPC exception area and
therefore calls the WarpHW API function 'InitBootArea'. This function
must return this location and should set up the hardware so that the
address space of the exception area (starting from 0xfff00000) is
mapped to the real location. This mapping can't be done by the MMU
since the exception area is located at physical address 0xfff00000.
Hardware logic should perform this mapping.
The exception area has to be located in writeable address space. The
API function is allowed to allocate the required memory. Note
that the exception area has to be aligned on a 64KB boundary and
must be at least 64KB large.
Note that the first 256 bytes of the exception area space are
reserved for the WarpUp HAL itself.
b) Resetting the PowerPC
After step a) the reset exception routine is prepared and some fields
of the exception area are initialized. After that, the PowerPC is
reset by calling the WarpHW API function 'BootPowerPC'. This function
should initialize all hardware registers and reset the PPC
processor which should start execution at 0xfff00100, where the
reset routine is located.
c) Causing the PowerPC interrupt
On dual processor systems, the WarpUp-HAL needs the possibility to
cause an external PPC interrupt by the 68K processor. In this case
the WarpHW API function 'CauseInterrupt' is called. This function
should drive the INT signal of the PPC to active state. The signal
should be kept in active state, until the interrupt was confirmed
by the PPC interrupt handler (by calling 'ConfirmInterrupt', see
below).
d) Confirming the PowerPC interrupt
After an external interrupt was caused from the 68K side, the
PowerPC enters into the external interrupt handler. This handler
calls the WarpHW API function 'ConfirmInterrupt' to confirm the
interrupt. This function should drive the INT signal to inactive
state.
6. API description
------------------
This chapter dicusses the API functions in more detail. For better
readability, they are written in autodoc format.
Note, that all API functions should preserve the smalldata base. Use
the keyword __saveds in the function declaration or use the template
sources.
Also note, that you can use the functions 'sync' (68K) and
'syncPPC' (PPC) to perform memory/command synchronisation. 'sync'
executes one NOP instruction, 'syncPPC' an ISYNC/SYNC pair. Both
functions can be found in the template project as assembler sources.
If the appropriate objects are present, just take them and link with
the other objects.
warpHW.library/GetDriverID warpHW.library/GetDriverID
NAME
GetDriverID - returns a driver identification string (V1)
CPU
680x0
MANDATORY
Yes
SYNOPSIS
IDstring = GetDriverID(void)
d0
char* GetDriverID(void)
FUNCTION
This function returns a string identifying this WarpUp hardware
driver. The string should be of the following format:
"WarpUp hardware driver for <hardware identification>"
The hardware identification must be unique across several
PPC hardware.
RESULT
IDstring - The identification string of this WarpUp hardware driver
warpHW.library/SupportedProtocol warpHW.library/SupportedProtocol
NAME
SupportedProtocol - returns the max. protocol version supported (V1)
CPU
680x0
MANDATORY
Yes
SYNOPSIS
Version = SupportedProtocol(void)
d0
int SupportedProtocol(void)
FUNCTION
This function returns a version number telling the WarpUp HAL the
highest driver protocol version which is supported by this driver.
This function exists for backward compatibility, so that the WarpUp
HAL won't call functions which don't exist in older hardware drivers.
RESULT
Version - The max. driver protocol version number supported
warpHW.library/InitBootArea warpHW.library/InitBootArea
NAME
InitBootArea - evaluates the address of the PowerPC exception area (V1)
CPU
680x0
MANDATORY
Yes
SYNOPSIS
ExcArea = InitBootArea(void)
d0
void *InitBootArea(void)
FUNCTION
This function returns the address of the PowerPC exception area.
This area must be in writeable address space and must be aligned
to a 64KB boundary and must be at least 64KB large.
The function should setup the hardware so that it maps the
physical address space of the exception area (starting with address
0xfff00000) to the real location of the exception area.
This function can allocate the memory itself and doesn't have to
care for memory freeing.
RESULT
ExcArea - Address of the PowerPC exception area
warpHW.library/BootPowerPC warpHW.library/BootPowerPC
NAME
BootPowerPC - resets the PowerPC (V1)
CPU
680x0
MANDATORY
Yes
SYNOPSIS
void BootPowerPC(void)
void BootPowerPC(void)
FUNCTION
This function resets the PowerPC processor which should start
execution at physical address 0xfff00100, where the reset
routine was installed by the WarpUp HAL.
In this function, all hardware registers which require initialization,
should be initialized.
warpHW.library/CauseInterrupt warpHW.library/CauseInterrupt
NAME
CauseInterrupt - trigger the PowerPC' external interrupt (V1)
CPU
680x0
MANDATORY
Yes
SYNOPSIS
void CauseInterrupt(void)
void CauseInterrupt(void)
FUNCTION
This function causes a PowerPC external interrupt. It should
drive the INT signal of the PowerPC to active state and should
keep it active, until the interrupt was confirmed from the PPC
side (see 'ConfirmInterrupt')
warpHW.library/ConfirmInterrupt warpHW.library/ConfirmInterrupt
NAME
ConfirmInterrupt - confirms the external interrupt (V1)
CPU
PowerPC
MANDATORY
Yes
SYNOPSIS
void ConfirmInterrupt(void)
void ConfirmInterrupt(void)
FUNCTION
This function is called from the WarpUp-HAL in the external
interrupt exception handler to confirm the interrupt. The
function should drive the INT signal to inactive state.
NOTES
This function is called with data cache frozen, therefore
any accesses which don't hit the cache are noncachable.
And the hardware registers should never be located in the
cache, since they are never accessed outside of
'ConfirmInterrupt' by the PowerPC.
7. Contact addresses
--------------------
regular mail: eMail:
HAAGE&PARTNER GmbH s.jordan@haage-partner.com
Mainzer Starße 10A
61191 Rosbach
Tel: 06007/930050
Fax: 06007/7543